home *** CD-ROM | disk | FTP | other *** search
/ AMP Graphics Collection / AMP Graphics Collection.iso / programs / author / versions / readme.mac < prev    next >
Text File  |  1996-08-09  |  19KB  |  357 lines

  1. Versions XObject for Windows
  2. ---------------------------
  3. Version 1.1, 8/9/96
  4. Copyright ⌐ 1996 Glenn M. Picher, Dirigo Multimedia
  5. Email: gpicher@maine.com
  6. Phone: 207/767-8015
  7. Web: http://www.maine.com/shops/gpicher
  8.  
  9. Distributor of registered version
  10. ------------------------------
  11. g/matter, inc.
  12. Email: support@gmatter.com
  13. Web: http://www.gmatter.com
  14. Phone: (415)243-0394
  15.  
  16. Detecting version, directory and file information with Versions
  17. ---------------------------------------------------------
  18. The Versions XObject for Windows detects QuickTime, DOS, Windows and 
  19. file versions. It's able to detect both Win16 and Win32 versions 
  20. and directories. It's also able to convert between MS-DOS short
  21. file names and Windows 95 / Windows NT long file names.
  22.  
  23. You can use the XObject for free to detect QuickTime version numbers 
  24. (both for 16-bit QuickTime and 32-bit QuickTime). You'll need to 
  25. register the XObject to use any of the other methods without showing 
  26. the copyright notice alert box.
  27.  
  28. The Versions XObject works with both Director 4 and Director 5.
  29. Even when running under Director 4 (always 16-bit) and under
  30. Director 5's 16-bit projectors, or the Director 5's 16-bit authoring 
  31. environment, the XObject is able to detect 32-bit version information
  32. by loading a small 32-bit application and 32-bit .DLL file
  33. (included with the XObject, and located in the same directory).
  34.  
  35. Sample cut-and-paste Lingo handlers are provided in the Director 4
  36. testbed movie that's provided with the XObject (using the method
  37. names without the initial "m", to match exactly the syntax 
  38. of global handler names in the planned release of a Lingo Xtra 
  39. version duplicating this XObject's functionality). You literally only 
  40. need to cut and paste one script castmember and make sure the required
  41. files are in the right directory in order to start using this XObject
  42. immediately. You needn't actually write any Lingo code to interface
  43. with the XObject directly. 
  44.  
  45. The Director 4 testbed movie opens and works fine without modification
  46. in Director 5. In addition to testing all methods, there are also 
  47. sample buttons to decide whether to install or update QuickTime; to 
  48. check the version number of the appropriate 16-bit or 32-bit version 
  49. of the primary Video for Windows file, MSVIDEO.DLL, in the appropriate
  50. System directory; a button to determine the appropriate 32-bit 
  51. System directory (which is a different directory that the 16-bit 
  52. System directory under Windows NT); and a button to identify
  53. the first shortcut in the Windows 95 Accessories menu (which 
  54. demonstrates the short / long file name conversion methods).
  55.  
  56. This XObject has been tested under Window 3.1, Windows 95 and Windows 
  57. NT. The only current limitation is that  Director 5 is not able to use
  58. inherently 16-bit XObjects from 32-bit projectors or the 32-bit 
  59. authoring environment under Windows NT; I anticipate releasing an .x32 
  60. Lingo Xtra version of this XObject soon to evade that restriction. 
  61. This XObject works fine with 16-bit Director 5 projectors, or Director
  62. 4's authoring environment and projectors, under Windows NT. 
  63. Unfortunately, the 16-bit Director 5 authoring environment doesn't run
  64. under Windows NT, so you have to do your Windows NT authoring on 
  65. another non-NT Windows machine if you want to use XObjects with 
  66. Director 5.
  67.  
  68. The Versions XObject's registered version is distributed by 
  69. g/matter, inc. in San Francisco. Contact information is above.
  70. Versions is one of several plug-ins that are useful in designing
  71. CDs that install and run automatcially on both Mac and Windows.
  72. Check my Web site again soon for other installation tools.
  73.  
  74. New version information
  75. -----------------------
  76. Version 1.0 of this XObject checked the 16-bit QuickTime version 
  77. within the XObject code itself (i.e., within Versions.DLL). However, 
  78. field reports indicated that Director 4 and 16-bit Director 5 would 
  79. sometimes get confused about the state of QuickTime (which the 
  80. XObject could affect), and would sometimes crash. Therefore,  
  81. version 1.1 completely insulates the QuickTime code from the Director 
  82. application itself by locating it in Vers16.DLL, which is loaded by 
  83. Ask16.EXE when the mQuickTimeVersion method is used. Be sure to 
  84. distribute those two additional files when you upgrade to this 
  85. version of the XObject.
  86.  
  87. New to version 1.1 of this XObject are the mGetShortFileName and 
  88. mGetLongFileName methods, which allow you to convert between MS-DOS 
  89. style '8.3' short file names and Windows 95 / Windows NT style 
  90. long file names (which can contain characters such as spaces that 
  91. are illegal in MS-DOS filenames). This may be necessary if you're 
  92. checking file versions of a known long-name file, or within a 
  93. known long-name directory. These methods can also be helpful 
  94. when using XObjects that are not aware of and don't work with 
  95. long file names.
  96.  
  97. Also new to version 1.1 is the mWinNTVersion method, which lets
  98. you check whick version of Windows NT your code is running under:
  99. Workstation, Server, or Advanced Server.
  100.  
  101. mDescribe documentation
  102. -----------------------
  103. Here's the XObject's complete table of methods, which provides some 
  104. minimal documentation. This is also available in Director's
  105. Message window, as usual, by sending an mDescribe message to the
  106. name of the XObject factory; that is, by typing...
  107.  
  108.   Versions(mDescribe)
  109.  
  110. Versions(mDescribe)
  111. -- Versions XObject, version 1.1, 8/9/96
  112. Versions
  113. -- Copyright ⌐ 1996 Glenn M. Picher, Dirigo Multimedia
  114. -- Email: gpicher@maine.com
  115. -- Web: http://www.maine.com/shops/gpicher
  116. -- Phone: (207)767-8015 (South Portland, Maine, USA)
  117. -- 
  118. -- Distributors: g/matter, inc.
  119. -- Email: support@gmatter.com
  120. -- Web: http://www.gmatter.com
  121. -- Phone: (415)243-0394 (San Francisco, California USA)
  122. -- 
  123. -- License granted to use and redistribute for any purpose,
  124. -- as long as copyright and contact information remains intact.
  125. -- Each instance of the XObject will present a copyright alert
  126. -- box once if you use any methods other than the QuickTime version
  127. -- checking functions. The registered version does not present any
  128. -- alert boxes.
  129. -- 
  130. I mNew           -- Standard creation method
  131. X mDispose       -- Standard dispose method
  132. S mQuickTimeVersion
  133. --  Get string of QuickTime version ('000000.000000.000000.000000' if QTW
  134. --  is not installed). Suitable for string comparisons (<, =, >). Example:
  135. --  Your title includes the QTW v2.1.1.57 installer, and you're running on
  136. --  a machine with QTW v2.0.1.41 already installed.  QTW v. 2.1.1.57 becomes
  137. --  '000002.000001.000001.000057' . Alphabetically, this comes after QTW
  138. --  v. 2.0.1.41 ('000002.000000.000001.000041'). Thus you can conclude
  139. --  that QuickTime needs to be updated to the version supplied with your
  140. --  title. This is a workaround for a bug in MCI 'info qtwvideo version'
  141. --  reporting, which does not always produce valid numeric comparisons. Only
  142. --  reports the 16-bit QuickTime version. Works by initializing QuickTime,
  143. --  so the first use may take much longer than subsequent uses.
  144. --  Number is formatted to be compatible with file version numbers.
  145. --  Note: requires ASK16.EXE and VERS16.DLL in the same directory as this
  146. --  XObject .DLL (these files are distributed with this XObject).
  147. --  Returns EMPTY if ASK16.EXE can't load; Returns string with word 1 'Error:'
  148. --  if ASK16.EXE fails. ***Note: version 1.0 of this XObject did not use
  149. --  ASK16.EXE and VERS16.DLL . To avoid occasional crashes when 16-bit Director
  150. --  got confused about the state of QuickTime, this new version keeps
  151. --  Director's QuickTime code isolated from this XObject's QuickTime
  152. --  code. Be sure to add ASK16.EXE and VERS16.DLL to your
  153. --  distributed projects when upgrading to this version of this XObject.
  154. S mWin32QuickTimeVersion
  155. --  Reports the 32-bit QuickTime version. Requires ASK32.EXE and VERS32.DLL
  156. --  in the same directory as this XObject .DLL . These files are
  157. --  distributed with this XObject .DLL file. Returns EMPTY if 32-bit
  158. --  environment is unavailable, or ASK32.EXE can't load; Returns
  159. --  string with word 1 'Error:' if ASK32.EXE fails.
  160. SS mFileVersion, fileName
  161. --  Get string of file version number. Allows checking versions of
  162. --  QuickTime compressor files, even 32-bit versions. Suitable for string
  163. --  comparisons. Example: QTIM32.DLL in the System folder, v. 2.1.1.57 becomes 
  164. --  '000002.000001.000001.000057' . The extra digits are the minimum required to
  165. --  represent the maximum 64-bit version number. Can be used with any file that
  166. --  contains a version resource, not just QuickTime files. If file is missing
  167. --  or does not contain version info, result is '000000.000000.000000.000000' .
  168. --  Works whether 32-bit environment is available or not; however,
  169. --  ASK32.EXE and VERS32.DLL are required in the same directory as this
  170. --  XObject .DLL to get Win32 version numbers under Windows NT or 95. These
  171. --  files are distributed with this XObject .DLL file. Further note: Windows
  172. --  NT uses a different system directory for 32-bit .DLLs. See below.
  173. S mWindowsDirectory
  174. --  Returns full path to Windows directory (including trailing '\').
  175. --  Useful for building full path names for use with mFileVersion.
  176. --  Word 1 of the returned string will be 'Error:' in the unlikely
  177. --  event of an error, followed by a description of the error.
  178. --  Note: returns the Win16 answer (see below).
  179. S mWin32WindowsDirectory
  180. --  Returns full path to Windows directory (including trailing '\').
  181. --  Should be the same answer as mWindowsDirectory for all current
  182. --  Windows versions, but this may change in future Win versions.
  183. --  Note: requires ASK32.EXE and VERS32.DLL in the same directory as this
  184. --  XObject .DLL (these files are distributed with this XObject).
  185. --  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
  186. --  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
  187. S mSystemDirectory
  188. --  Returns full path to System directory (including trailing '\').
  189. --  Useful for building full path names for use with mFileVersion.
  190. --  Word 1 of the returned string will be 'Error:' in the unlikely
  191. --  event of an error, followed by a description of the error.
  192. --  Note: returns the Win16 answer (see below).
  193. S mWin32SystemDirectory
  194. --  Returns full path to System directory (including trailing '\').
  195. --  Under Windows NT, this is a different answer than mSystemDirectory.
  196. --  Note: requires ASK32.EXE and VERS32.DLL in the same directory as this
  197. --  XObject .DLL (these files are distributed with this XObject).
  198. --  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
  199. --  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
  200. S mDOSVersion
  201. --  Returns the DOS version reported to 16-bit apps. No Win32 equivalent.
  202. S mWindowsVersion
  203. --  Returns the Windows version reported to 16-bit apps. This is
  204. --  not the same answer as mWin32Version under Windows 95.
  205. S mWin32Version
  206. --  Returns the Win32 version (a different answer than mWindowsVersion)
  207. --  Note: requires ASK32.EXE and VERS32.DLL in the same directory as this
  208. --  XObject .DLL (these files are distributed with this XObject).
  209. --  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
  210. --  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
  211. --  Note the lack of ability to check for Win32-specific DOS version.
  212. S mWin32Platform
  213. --  Returns the Win32 platform ('Win32s on Windows 3.1',
  214. --  'Win32 on Windows 95', or 'Windows NT').
  215. --  Note: requires ASK32.EXE and VERS32.DLL in the same directory as this
  216. --  XObject .DLL (these files are distributed with this XObject).
  217. --  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
  218. --  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
  219. S mWin32Build
  220. --  Returns the Win32 build. This is useful because Director requires
  221. --  at least Windows NT v3.51 with Service Pack 4 applied (build 1057).
  222. --  Note: requires ASK32.EXE and VERS32.DLL in the same directory as this
  223. --  XObject .DLL (these files are distributed with this XObject).
  224. --  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
  225. --  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
  226. S mWinNTVersion
  227. --  Tells you what verison of Windows NT you're running under-- 'Workstation',
  228. --  'Server', 'Advanced Server', 'Unknown', or 'Error' is there's a problem. 
  229. --  Note: requires ASK32.EXE and VERS32.DLL in the same directory as this
  230. --  XObject .DLL (these files are distributed with this XObject).
  231. --  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
  232. --  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
  233. SS mGetShortFileName, theFile
  234. --  Returns the MS-DOS style filename of a Windows 95 or Windows NT long
  235. --  file name which might contain spaces or other DOS-illegal characters. 
  236. --  This method can also accept file names that are already DOS-legal. 
  237. --  This method is helpful when an XObject only works with DOS filenames.
  238. --  Note: requires ASK32.EXE and FNAME32.DLL in the same directory as this
  239. --  XObject .DLL (these files are distributed with this XObject).
  240. --  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
  241. --  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
  242. SS mGetLongFileName, theFile
  243. --  Returns the Windows 95 or Windows NT long file name, which might contain
  244. --  spaces or other DOS-illegal characters, given a DOS short file name. 
  245. --  This method can also accept file names that are already long.
  246. --  Note: requires ASK32.EXE and FNAME32.DLL in the same directory as this
  247. --  XObject .DLL (these files are distributed with this XObject).
  248. --  Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE
  249. --  can't load; Returns string with word 1 'Error:' if ASK32.EXE fails.
  250. -- 
  251.  
  252. Of historical interest: Why the Versions XObject?
  253. --------------------------------------------
  254. Initially, the Versions XObject was created to work around a bug in the 
  255. MCI interface to QuickTime for Windows. When requesting QuickTime version 
  256. numbers using...
  257.  
  258.     mci "info qtwvideo version"
  259.     put the result
  260.  
  261. ...the reported number would not report decimal point placement 
  262. consistently across different version of QuickTime for Windows. This made 
  263. it rather difficult to determine whether the user should update QuickTime 
  264. with the version of the QuickTime for Windows installer you provided with 
  265. your title.
  266.  
  267. However, the question of version numbers proved more subtle with Apple's 
  268. introduction of 16-bit and 32-bit flavors of QuickTime for Windows 
  269. beginning with version 2.1.1 in the spring of 1996. It's only possible 
  270. to detect the 16-bit QuickTime version from a 16-bit app or .dll, and 
  271. you can only know the 32-bit QuickTime version from a 32-bit app or 
  272. .dll . XObjects are inherently 16-bit code, and so always return a 
  273. 16-bit answer to questions such as these. To make things more confusing, 
  274. the MCI interface to QuickTime for Windows could report a 16-bit version 
  275. number to a 32-bit application (Director 5), even though the application, 
  276. using the C rather than the MCI interface to QuickTime, required the 
  277. 32-bit version.
  278.  
  279. The mFileVersion method was intended to work around this limitation by 
  280. checking for a file version resource in particularly named files in the 
  281. System directory (such as QTIM32.DLL). However, there are a number of  
  282. problems with this approach. The existence of a file alone does not 
  283. confirm proper configuration. Furthermore, certain .DLLs have file 
  284. version resources that can only be read from 32-bit code running on a 
  285. 32-bit platform (such as WIndows NT system files); they can't be 
  286. identified from 16-bit code. Finally, Windows NT places 32-bit .DLL 
  287. files into a different directory than 16-bit .DLLs, and the name of that 
  288. directory can only be detected from 32-bit code.
  289.  
  290. The solution was to write a 32-bit application which called a 32-bit 
  291. .DLL to get 32-bit answers to these configuration questions. This 32-bit 
  292. application (Ask32.exe) is launched by the 16-bit XObject .DLL file, and 
  293. the two tasks communicate with each other to access the requested 
  294. information.  Ask32.exe and Vers32.dll must be distributed in the same 
  295. directory as Versions.dll to work properly on Win32 platforms such as 
  296. Windows 95 and Windows NT.
  297.  
  298.  
  299. Known bugs:
  300. -----------
  301. None.
  302.  
  303. Known limitations:
  304. ------------------
  305. Does not operate under Windows NT with 32-bit Director 5's authoring
  306. environment or Director 5's 32-bit projector. This is true of any
  307. XObject. 
  308.  
  309. This XObject should be used in an initial Director movie that does *not*
  310. contain any QuickTime castmembers. Director itself will display an 
  311. ungraceful message about the need for QuickTime when a movie is 
  312. loaded, if any QuickTime castmember are found in the movie, *before* 
  313. you get a chance to use the Versions XObject.
  314.  
  315. The QuickTime version methods are rather slow, because not only
  316. do they fully initialize QuickTime and all its .DLL files, but 
  317. the code itself is run from a separate .EXE file loaded by this
  318. XObject. Little can be done to speed this process up.
  319.  
  320. Revision history:
  321. -----------------
  322. 8/9/96: Version 1.1
  323.     Isolated QuickTime code from Director's code in mQuickTimeVersion
  324.     method by using Ask16.EXE and Vers16.DLL . This eliminates some
  325.     confusion and possible crashes when Versions was used from 16-bit
  326.     Director executables.
  327.  
  328.     Added mGetShortFileName, mGetLongFileName, and mWinNTVersion
  329.     methods.
  330.  
  331.     Added more information to Read Me document.
  332.  
  333. 6/26/96: Version 1.0
  334.     16 and 32 bit methods.
  335.  
  336. 6/8/96: Version 0.9 beta
  337.     16-bit only methods.
  338.  
  339. Standard legal disclaimer
  340. -------------------------
  341. This software is provided "as is" without warranty of any kind, either
  342. expressed or  implied, including, but not limited to, the implied
  343. warranties of merchantability or fitness for a particular purpose.
  344. The software or its documentation or sample code may include errors
  345. or technical inaccuracies. Changes are periodically made to this
  346. software, its documentation and sample code, and may be incorporated
  347. in new versions. Dirigo Multimedia and g/matter may improve or
  348. change their products at any time without notice.  Dirigo Multimedia
  349. and g/matter assume no responsibility for and disclaim all
  350. liability for errors in this software or its documentation and sample
  351. code.  Neither Dirigo Multimedia nor g/matter will be responsible for
  352. any damages of any sort under any conditions. While the Versions
  353. XObject contains no known bugs, use it at your own risk. As always,
  354. you should make frequent backups of important information.
  355. Some jurisdictions do not allow the exclusion of implied
  356. warranties, so the above exclusion may not apply to you.
  357.